.\" $Id: PAPI_register_thread.3,v 1.6 2004/09/30 17:29:24 london Exp $
.TH PAPI_register_thread 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_register_thread, PAPI_unregister_thread \- Inform PAPI of thread status

.SH SYNOPSIS
.nf
.B #include <papi.h>
.BI "int PAPI_register_thread (void);"
.BI "int PAPI_unregister_thread (void);"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_register_thread(C_INT\  check )
.BI PAPIF_unregister_thread(C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_register_thread
should be called when the user wants to force PAPI to initialize 
a thread that PAPI has not seen before. Usually this is
not necessary as PAPI implicitly detects the thread when an eventset is
created or other thread local PAPI functions are called. However, it can
be useful for debugging and performance enhancements in the run-time systems
of performance tools.
.LP
.B PAPI_unregister_thread
should be called when the user wants to shutdown a particular thread and
free the associated thread ID. THIS IS IMPORTANT IF YOUR THREAD 
LIBRARY REUSES THE SAME THREAD ID FOR A NEW KERNEL LWP. OpenMP does this.
OpenMP parallel regions, if separated by a call to omp_set_num_threads() 
will often kill off the underlying kernel LWPs and then start new ones for the
next region. However, omp_get_thread_id() does not reflect this, as the thread
IDs for the new LWPs will be the same as the old LWPs. PAPI needs to know that
the underlying LWP has changed so it can set up the counters for that new 
thread. This is accomplished by calling this function.

.SH ARGUMENTS
None.

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_ENOMEM"
Space could not be allocated to store the new thread information.
.TP
.B "PAPI_ESYS"
A system or C library call failed inside PAPI, see the 
.I "errno"
variable.
.TP
.B "PAPI_ESBSTR"
Hardware counters for this thread could not be initialized.

.SH EXAMPLES
None.

.SH SEE ALSO
.BR PAPI_thread_init "(3), "
.BR PAPI_thread_id "(3) "

